Sdg23 update user guide installation instructions by namiroues · Pull Request #404 · MDAnalysis/UserGuide

namiroues · 2025-02-23T15:57:25Z

This PR updates the installation instructions in the User Guide as part of the SDG documentation cleanup.

This PR is linked to MDAnalysis/mdanalysis#4927

This PR fixes #402 and #405

📚 Documentation preview 📚: https://mdanalysisuserguide--404.org.readthedocs.build/en/404/

lilyminium

Awesome work @namiroues! I've just left some non-blocking recommendations to separate links or maybe use refs to streamline the text a bit.

doc/source/installation.rst

…ments

namiroues · 2025-03-04T16:46:25Z

Hi @lilyminium, thanks a lot for the comments, I addressed them and I also refined the instructions to have a clearer version.

namiroues · 2025-03-04T16:50:15Z

Hi @micaela-matta could you please check the changes?

orbeckst

Please see comments inline, sorry to be brief.

doc/source/installation.rst

* Fixes #4929 * Removed duplicate installation instructions from API Docs * related to MDAnalysis/UserGuide#404

namiroues · 2025-03-22T20:27:26Z

Thanks @orbeckst for your comments. I've updated the installation instructions. I also updated other parts that were outdated. Please have a look. I am sure that you will have some more comments for me :).

orbeckst

Great rewrite.

I found a few things that occurred to me (and which are generally not that obvious). Thank you for updating this page, it's been high time for an update.

doc/source/installation.rst

namiroues · 2025-03-23T08:37:41Z

Thanks @orbeckst for your comments. I've addressed them.

orbeckst

Last check before approving: Have you followed the installation instructions and can you confirm that they work?

(I had minor changes but I added them myself from suggestions.)

doc/source/installation.rst

orbeckst · 2025-03-24T00:37:29Z

The pre-commit hook check is failing for me. I am just editing on GitHub so I can't easily see where the trailing whitespace is. Can you please run it locally through your pre-commit hook to fix it, @namiroues ? Thanks.

lilyminium

I haven't tested the installation instructions myself, but otherwise LGTM! Thanks for all your work @namiroues, looks excellent!

micaela-matta

I second @orbeckst's request to double check installation instructions, but other that that, LGTM! thanks @namiroues

RMeli

Thanks @namiroues, looks very good! I left some additional comments.

doc/source/installation.rst

orbeckst · 2025-03-28T06:47:37Z

The RTD build failed because a package had the wrong checksum. I assume that this is an intermittent error (which is out of our control) and it will work the next time you push to this PR.

namiroues · 2025-03-28T19:33:35Z

Thanks @orbeckst and @RMeli for your comments. I addressed the comments and tested the installation instructions. They work for me with conda-forge (so I explicitly added this). Can someone try a fresh installation with mambaforge to double-test this?

orbeckst

Minor changes inline, the instructions themselves seem good, but not everything works. I kept notes for future follow-up.

Notes from testing on macOS x86_64

❌ mamba Python 3.13.2

I tried in an existing conda/mamba installation. By default it created a Python 3.13.2 environment. MDAnalysis installed fine:

>>> python -c "import MDAnalysis; print(MDAnalysis.__version__)"
2.9.0

However, MDAnalysisTests has issues for me:

mamba install -c conda-forge MDAnalysisTests

gives

Getting  conda-forge osx-64
Getting  conda-forge noarch

Looking for: ['mdanalysistests', 'python 3.13.2']

509175 packages in https://conda.anaconda.org/conda-forge/osx-64
259522 packages in https://conda.anaconda.org/conda-forge/noarch
Encountered problems while solving.
Problem: nothing provides mdanalysis 0.15.0 needed by mdanalysistests-0.15.0-py27_0

I have no idea why it wants to install 0.15.

Then I try pinning

mamba install -c conda-forge "MDAnalysisTests=2.9.0"

and that fails with

Looking for: ['mdanalysistests 2.9.0.*', 'python 3.13.2']

509175 packages in https://conda.anaconda.org/conda-forge/osx-64
259522 packages in https://conda.anaconda.org/conda-forge/noarch
Encountered problems while solving.
Problem: package mdanalysistests-2.9.0-pyhd8ed1ab_0 requires python >=3.9,<=3.13, but none of the providers can be installed

The mdanalysistests condaforge recipe contains https://github.com/conda-forge/mdanalysistests-feedstock/blob/c9c9a496f8172b2bc9a5c7571092e2ab2f1f8c2f/recipe/meta.yaml#L25

    - python >=3.9,<=3.13

Based on the package match specification this seems to be the issue because it will not match Python 3.13.2.

I raised conda-forge/mdanalysistests-feedstock#51, which has already been fixed. (So need to test with conda -forge packages ...)

✅ mamba Python 3.12

mamba create -n mdanalysis -c conda-forge mdanalysis python=3.12
mamba activate mdanalysis
mamba install -c conda-forge MDAnalysisTests

Tests in parallel

pytest --disable-pytest-warnings -n 2 -v --pyargs MDAnalysisTests

were a bit wonky for me. Deadlocked once around 87%, second time it happened I started killing python3.12 processes and then suddenly tests continued to run (although possibly only in one runner). Tried again

pytest --disable-pytest-warnings -n 4 -v --pyargs MDAnalysisTests

succeeded (installs 2.9.0 and tests pass).

============ 19714 passed, 363 skipped, 7 xfailed, 2 xpassed, 107840 warnings in 749.94s (0:12:29) ============

✅ , ❌ pip 3.13

Create mamba env with python 3.13

mamba create -n mdapip313 python=3.13 pip

✅ standard

and installed with

pip install --upgrade MDAnalysis
pip install --upgrade MDAnalysisTests

Tests

pytest --disable-pytest-warnings -n 2 -v --pyargs MDAnalysisTests

passed

============ 19014 passed, 781 skipped, 6 xfailed, 2 xpassed, 89945 warnings in 962.55s (0:16:02) =============

❌ Installing extras

pip install --upgrade MDAnalysis[analysis,extra_formats,parallel]

failed because pytng did not build

...
      pytng/pytng.c:2398:22: error: implicit declaration of function '_PyList_Extend' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
          PyObject* none = _PyList_Extend((PyListObject*)L, v);
                           ^
...
      pytng/pytng.c:2436:39: error: implicit declaration of function '_PyInterpreterState_GetConfig' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
          __pyx_assertions_enabled_flag = ! _PyInterpreterState_GetConfig(__Pyx_PyThreadState_Current->interp)->optimization_level;
                                            ^
      pytng/pytng.c:2436:107: error: member reference type 'int' is not a pointer
          __pyx_assertions_enabled_flag = ! _PyInterpreterState_GetConfig(__Pyx_PyThreadState_Current->interp)->optimization_level;
                                            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  ^
...
      pytng/pytng.c:34856:13: error: implicit declaration of function '_PyUnicode_FastCopyCharacters' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
                  _PyUnicode_FastCopyCharacters(result_uval, char_pos, uval, 0, ulength);
                  ^
...
      pytng/pytng.c:38679:70: error: too few arguments to function call, expected 6, have 5
                                                    is_little, !is_unsigned);
                                                                           ^
...
      pytng/pytng.c:34856:13: error: implicit declaration of function '_PyUnicode_FastCopyCharacters' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
                  _PyUnicode_FastCopyCharacters(result_uval, char_pos, uval, 0, ulength);
                  ^
...
      pytng/pytng.c:38679:70: error: too few arguments to function call, expected 6, have 5
                                                    is_little, !is_unsigned);
                                                                           ^
...
              #define Py_EXPORTED_SYMBOL __attribute__ ((visibility ("default")))
                                         ^
      pytng/pytng.c:39895:13: error: implicit declaration of function '_PyGen_SetStopIterationValue' is invalid in C99 [-Werror,-Wimplicit-function-declaration]
                  _PyGen_SetStopIterationValue(result);
                  ^
...
      22 warnings and 9 errors generated.
      error: command '/usr/bin/clang' failed with exit code 1
      [end of output]

...

Failed to build pytng
ERROR: Failed to build installable wheels for some pyproject.toml based projects (pytng)

doc/source/installation.rst

orbeckst

Source installation instructions do not work as written.

Please fix/clarify.

doc/source/installation.rst

namiroues · 2025-03-31T07:36:31Z

Thanks @orbeckst. I fixed it and tested it myself.

orbeckst

Good rewrite, all perfect from my end.

orbeckst · 2025-03-31T16:31:49Z

Nice work, @namiroues !

…#4927) * Fixes MDAnalysis#4929 * Removed duplicate installation instructions from API Docs * related to MDAnalysis/UserGuide#404

namiroues added 2 commits February 21, 2025 20:19

Redesign installation guide in User Guide

29e29fd

final clear version of Installation Guide

556788f

namiroues changed the title ~~Sdg23 update user guide~~ Sdg23 update user guide installation instructions Feb 23, 2025

namiroues mentioned this pull request Feb 23, 2025

Removed duplicate installation instructions from API Docs MDAnalysis/mdanalysis#4927

Merged

5 tasks

lilyminium reviewed Mar 1, 2025

View reviewed changes

doc/source/installation.rst Outdated Show resolved Hide resolved

doc/source/installation.rst Outdated Show resolved Hide resolved

doc/source/installation.rst Outdated Show resolved Hide resolved

orbeckst added this to Streamlining Documentation (SDG23) Mar 1, 2025

orbeckst moved this to In Progress in Streamlining Documentation (SDG23) Mar 1, 2025

update installation instructions in User Guide and address review com…

da287f2

…ments

namiroues assigned orbeckst, micaela-matta and jennaswa Mar 4, 2025

orbeckst requested changes Mar 4, 2025

View reviewed changes

orbeckst pushed a commit to MDAnalysis/mdanalysis that referenced this pull request Mar 14, 2025

Removed duplicate installation instructions from API Docs (#4927)

9d072d9

* Fixes #4929 * Removed duplicate installation instructions from API Docs * related to MDAnalysis/UserGuide#404

Address PR review comments and update outdated content

ed4772d

namiroues requested review from micaela-matta and orbeckst March 22, 2025 20:27

orbeckst requested changes Mar 23, 2025

View reviewed changes

address PR review comments

d0f1936

namiroues requested review from lilyminium and orbeckst March 23, 2025 08:37

namiroues unassigned micaela-matta and jennaswa Mar 23, 2025

orbeckst requested changes Mar 24, 2025

View reviewed changes

doc/source/installation.rst Outdated Show resolved Hide resolved

doc/source/installation.rst Show resolved Hide resolved

orbeckst mentioned this pull request Mar 24, 2025

2.9 release of the userguide #415

Closed

lilyminium approved these changes Mar 24, 2025

View reviewed changes

micaela-matta approved these changes Mar 24, 2025

View reviewed changes

orbeckst linked an issue Mar 24, 2025 that may be closed by this pull request

installation instructions suggest incorrect mamba installation #405

Closed

RMeli reviewed Mar 24, 2025

View reviewed changes

orbeckst mentioned this pull request Mar 24, 2025

Replace fasteners dependency to filelock #400

Closed

orbeckst reviewed Mar 25, 2025

View reviewed changes

doc/source/installation.rst Outdated Show resolved Hide resolved

Fix pre-commit: trim trailing whitespace and ensure EOF newline"

5ef1085

namiroues force-pushed the sdg23-update-user-guide branch from 4fcc12e to 5ef1085 Compare March 26, 2025 17:16

address PR review comments

61efd5e

fix missing newline at end of installation.rst

cb102d9

namiroues requested a review from orbeckst March 28, 2025 19:37

orbeckst requested changes Mar 29, 2025

View reviewed changes

doc/source/installation.rst Outdated Show resolved Hide resolved

doc/source/installation.rst Outdated Show resolved Hide resolved

orbeckst added 2 commits March 29, 2025 02:02

Update doc/source/installation.rst

e016913

Update doc/source/installation.rst

1184152

orbeckst approved these changes Mar 29, 2025

View reviewed changes

orbeckst requested changes Mar 29, 2025

View reviewed changes

doc/source/installation.rst Outdated Show resolved Hide resolved

address PR review comments

21de04a

namiroues requested a review from orbeckst March 31, 2025 07:36

orbeckst approved these changes Mar 31, 2025

View reviewed changes

orbeckst merged commit 55ca9a3 into MDAnalysis:develop Mar 31, 2025
4 checks passed

github-project-automation bot moved this from In Progress to Done in Streamlining Documentation (SDG23) Mar 31, 2025

Conversation

namiroues commented Feb 23, 2025 • edited by orbeckst Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lilyminium left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

namiroues commented Mar 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

namiroues commented Mar 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

orbeckst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

namiroues commented Mar 22, 2025

Uh oh!

orbeckst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

namiroues commented Mar 23, 2025

Uh oh!

orbeckst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

orbeckst commented Mar 24, 2025

Uh oh!

lilyminium left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

micaela-matta left a comment

Choose a reason for hiding this comment

Uh oh!

RMeli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

orbeckst commented Mar 28, 2025

Uh oh!

namiroues commented Mar 28, 2025

Uh oh!

orbeckst left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Notes from testing on macOS x86_64

❌ mamba Python 3.13.2

✅ mamba Python 3.12

✅ , ❌ pip 3.13

✅ standard

❌ Installing extras

Uh oh!

namiroues commented Feb 23, 2025 •

edited by orbeckst

Loading

namiroues commented Mar 4, 2025 •

edited

Loading

namiroues commented Mar 4, 2025 •

edited

Loading

lilyminium left a comment •

edited

Loading

orbeckst left a comment •

edited

Loading